xwiki 文档迁移到 confluence-(2) 如何将上传的 pdf 显示在 confluence 页面中

xwiki 文档迁移到 confluence-(2) 如何将上传的 pdf 显示在 confluence 页面中

  • 2018-12-25

这是整个迁移过程中毕竟关键的一步, 也是为了实现友好的查看文档的关键步骤.前文中已经知道了怎么直接在页面中显示 PDF.

1

接下来就通过程序来实现.这个过程还是稍微有点复杂的, 所以也是作为一个单独的小节来写.

首选还是得通过抓包来总结出整个过程中都经历了哪些请求:

1
上传文件 -> 插入附件 -> 更新

下面就以上面的流程来进行描述.虽然下面的流程看似也不复杂, 不过需要一步步的进行摸索, 其中也可能遇到一些问题, 需要不断的反复进行抓包实验.

上传文件

上传文件这一步我们不要通过页面中的请求来做, 这个稍微复杂了一点.confluence 提供了 restful api 可以将附件上传到文档中.

具体可见: https://docs.atlassian.com/ConfluenceServer/rest/6.12.2/#content/{id}/child/attachment-createAttachments

1
上传附件: /rest/api/content/{id}/child/attachment

插入附件

插入附件需要进行如下的请求:

1
/rest/tinymce/1/macro/placeholder

2

请求的 JSON 格式稍微解释下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
	// wiki page 的 id
	"contentId": "2818258",
	"macro": {
		// 固定值
		"name": "view-file",
		"params": {
			// 文件名称
			"name": "测试文档1.pdf",
			// 可以传固定值
			"height": "250"
		}
	}
}

返回的内容是一串字符串, 这个字符的值我们需要保存下, 作为后续请求的信息.
不过我们要注意上面返回的字符串中 src 后面的内容:

3

可以看到, 返回的是类似于 /plugins/servlet/view-file-macro/placeholder?type=PDF+Document 的信息.不过也可能会返回如下的信息:

4

这次返回的是类似于 /rest/documentConversion/latest/conversion/thumbnail/4849682/1?attachmentId= 的请求.

是不是有点疑惑, 确实是让人感觉很奇怪.怎么会出现这样的现象, 上面的情形是通过如下的操作得以复现的:

5

准确的来说, 后续请求是要发送类似于 /rest/documentConversion/latest/conversion/thumbnail/4849682/1?attachmentId= 这样的信息而不是 /plugins/servlet/view-file-macro/placeholder?type=PDF+Document 这样的信息.现在先结束关于这个问题的探讨, 后续再接着探索.

插入附件请求之后还没结束, 没法直接进行更新请求.这也是在实验过程中遇到的一个问题.还需要等待文档转换完成.

文档转换结果查询

文档转换结果查询需要调用下面的请求:

1
查询文档转换结果: /rest/documentConversion/latest/conversion/thumbnail/results

6

上面的文档转换请求只有两次, 但是实际情况中并一定是 2 次, 我们需要进行多次查询, 如果是 202, 就休眠一会再继续查询, 直到返回码是 200 为止.

发送 drafts 请求

drafts 是草稿的意思, 意思就是我们得接着再发起一个草稿(drafts)的请求.

1
/rest/tinymce/1/drafts

7

注意上面的 content 内容, 如果是类似于 /plugins/servlet/view-file-macro 的, 我们需要转换为 /rest/documentConversion 相关的, 这个怎么转换, 其实不难, 就是进行替换而已, 通过比较两种信息, 可以很容易发现该怎么进行转换, 示例如下:

1
2
3
<img class="editor-inline-macro" height="250" src="/plugins/servlet/view-file-macro/placeholder?type=PDF+Document&amp;name=%E6%B5%8B%E8%AF%95xxx.pdf&amp;attachmentId=2490399&amp;version=1&amp;mimeType=application%2Fpdf&amp;height=250&amp;thumbnailStatus=202" data-macro-name="view-file" data-macro-parameters="height=250|name=测试xxx.pdf" data-macro-schema-version="1">

<img class="editor-inline-macro" height="250" src="/rest/documentConversion/latest/conversion/thumbnail/2490399/1?attachmentId=2490399&amp;version=1&amp;mimeType=application%2Fpdf&amp;height=250&amp;thumbnailStatus=200" data-macro-name="view-file" data-macro-parameters="height=250|name=测试xxx.pdf" data-macro-schema-version="1">

更新 drafts

上面的操作都完成之后, 接下来要做的就是最后的确认更新操作:

1
/rest/api/content/{id}?status=draft

8

到这里为止, 我们展示了上传附件到 confluence, 以及如何将 PDF 文件显示在页面中.

整个过程稍微复杂了一点, 不过也不是很难.有些请求并没有对应的文档说明, 需要我们自己探索, 做实验进行验证.

最终用一张图示总结下所涉及的过程:

9

xwiki 文档迁移到 confluence-(3) 遇到的坑及注意事项
Swagger bug-当 http 请求方法是 get 时 Operation.getConsumes() 不应该返回 application/json